Programming With QuickTime VR
| Previous | Chapter Contents | Chapter Top | Next |
The QuickTime VR Manager provides a number of routines that you can use to handle user actions such as moving the mouse or clicking the mouse button. Normally, QuickTime VR handles all user interaction internally if your application calls the MCIsPlayerEvent function in its main event loop. For code that does not have a main event loop (such as an OpenDoc part), you might need to override QuickTime VR's mouse event handling.
Most applications do not need to use the functions described in this section.
You can use the QTVRGetMouseOverTracking function to get the current state of mouse-over tracking.
Boolean QTVRGetMouseOverTracking (QTVRInstance qtvr);
The QTVRGetMouseOverTracking function returns, as its function result, a Boolean value that indicates whether QuickTime VR is currently handling mouse-over tracking for the QuickTime VR movie specified by the qtvr parameter ( true ) or not ( false ). By default, QuickTime VR tracks mouse movements in a QuickTime VR movie and changes the shape of the cursor as appropriate.
You can use the QTVRSetMouseOverTracking function to set the state of mouse-over tracking.
OSErr QTVRSetMouseOverTracking (QTVRInstance qtvr, Booleanenable);
The QTVRSetMouseOverTracking function sets the mouse-over tracking state of the QuickTime VR movie specified by the qtvr parameter to the state specified by the enable parameter. By default, QuickTime VR tracks mouse movements in a QuickTime VR movie and changes the shape of the cursor as appropriate. If you disable mouse-over tracking (by passing false in the enable parameter), you must call the QTVRMouseEnter , QTVRMouseWithin , and QTVRMouseLeave functions at the appropriate times to handle user actions.
Use QTVRGetMouseOverTracking to get the current mouse-over tracking state of a QuickTime VR movie.
You can use the QTVRMouseEnter function to handle the user's moving the cursor into a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseEnter (
QTVRInstance qtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseEnter function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseEnter also performs any other tasks that are typically performed when the user first moves the cursor into a QuickTime VR movie.
You need to call QTVRMouseEnter only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseWithin (next) and QTVRMouseLeave to handle the cursor's remaining in and leaving a QuickTime VR movie.
You can use the QTVRMouseWithin function to handle the user's leaving the cursor in a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseWithin (QTVRInstance qtvr, Pointpt, UInt32*hotSpotID, WindowPtr w);
The QTVRMouseWithin function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseWithin also performs any other tasks that are typically performed when the user leaves the cursor in a QuickTime VR movie.
You should call QTVRMouseWithin repeatedly for as long as the cursor remains in the specified QuickTime VR movie.
You need to call QTVRMouseWithin only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseEnter and QTVRMouseLeave (next) to handle the cursor's entering and leaving a QuickTime VR movie.
You can use the QTVRMouseLeave function to handle the user's moving the cursor out of a QuickTime VR movie for which mouse-over tracking is disabled.
OSErr QTVRMouseLeave (QTVRInstance qtvr, Pointpt, WindowPtr w);
The QTVRMouseLeave function performs any tasks that are typically performed when the user moves the cursor out of a QuickTime VR movie.
You need to call QTVRMouseLeave only if you have disabled mouse-over tracking for the specified QuickTime VR movie.
Use QTVRSetMouseOverTracking to change the mouse-over tracking state of a QuickTime VR movie. Use QTVRMouseEnter and QTVRMouseWithin to handle the cursor's entering and remaining in a QuickTime VR movie.
You can use the QTVRGetMouseDownTracking function to get the current state of mouse-down tracking.
Boolean QTVRGetMouseDownTracking (QTVRInstanceqtvr);
The QTVRGetMouseDownTracking function returns, as its function result, a Boolean value that indicates whether QuickTime VR is currently handling mouse-down tracking for the QuickTime VR movie specified by the qtvr parameter ( true ) or not ( false ). By default, QuickTime VR tracks mouse clicks in a QuickTime VR movie and triggers hot spots as necessary.
You can use the QTVRSetMouseDownTracking function to set the state of mouse-down tracking.
OSErr QTVRSetMouseDownTracking (QTVRInstance qtvr, Booleanenable);
The QTVRSetMouseDownTracking function sets the mouse-down tracking state of the QuickTime VR movie specified by the qtvr parameter to the state specified by the enable parameter. By default, QuickTime VR tracks mouse clicks in a QuickTime VR movie and triggers hot spots as appropriate. If you disable mouse-down tracking (by passing false in the enable parameter), you must call the QTVRMouseDown , QTVRMouseStillDown , and QTVRMouseUp functions at the appropriate times to handle user actions.
Use QTVRGetMouseDownTracking to get the current mouse-down tracking state of a QuickTime VR movie.
You can use the QTVRMouseDown function to handle the user's clicking the mouse button when the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
OSErr QTVRMouseDown (QTVRInstanceqtvr,
Pointpt,
UInt32 when,
UInt16 modifiers,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseDown function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseDown also performs any other tasks that are typically performed when the user clicks the mouse button when the cursor is in a QuickTime VR movie.
You need to call QTVRMouseDown only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseUp and QTVRMouseStillDown (next) to handle the mouse button's being held down and released.
You can use the QTVRMouseStillDown function to handle the user's holding down the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
Applications running on operating systems other than Mac OS should use the extended form of this function: see "QTVRMouseStillDownExtended" .
OSErr QTVRMouseStillDown (
QTVRInstanceqtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w);
The QTVRMouseStillDown function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseStillDown also performs any other tasks that are typically performed when the user holds down the mouse button when the cursor is in a QuickTime VR movie.
You should call QTVRMouseStillDown repeatedly for as long as the user holds down the mouse button while the cursor is in the specified QuickTime VR movie.
You need to call QTVRMouseStillDown only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown and QTVRMouseUp (next) to handle the mouse button's being clicked and released.
You can use the QTVRMouseUp function to handle the user's releasing the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
Applications running on operating systems other than Mac OS should use the extended form of this function: see "QTVRMouseUpExtended" .
OSErr QTVRMouseUp (QTVRInstance qtvr, Pointpt, UInt32*hotSpotID, WindowPtr w);
The QTVRMouseUp function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseUp also performs any other tasks that are typically performed when the user releases the mouse button after clicking it when the cursor is in a QuickTime VR movie.
You need to call QTVRMouseUp only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown and QTVRMouseStillDown to handle the mouse button's being clicked and held down.
You can use the QTVRMouseStillDownExtended function the same way you use the QTVRMouseStillDown function, to handle the user's holding down the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
The QTVRMouseStillDownExtended function uses the same intercept as the QTVRMouseStillDown function but has two additional parameters. Applications that intercept kQTVRMouseStillDownExtended should always check the paramCount field to make sure it is 5 before using the last two fields.
Internally, QuickTime VR always uses the QTVRMouseStillDownExtended function instead of QTVRMouseStillDown . Developers implementing their own mouse down tracking don't need to use the extended version unless they also intercept the procedure and need the added parameters.
OSErr QTVRMouseStillDownExtended (
QTVRInstanceqtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w,
UInt32 when,
UInt16 modifiers);
The QTVRMouseStillDownExtended function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseStillDownExtended also performs any other tasks that are typically performed when the user holds down the mouse button when the cursor is in a QuickTime VR movie.
You should call QTVRMouseStillDownExtended repeatedly for as long as the user holds down the mouse button while the cursor is in the specified QuickTime VR movie.
You need to call QTVRMouseStillDownExtended only if you have disabled mouse-down tracking for the specified QuickTime VR movie.
Use QTVRSetMouseDownTracking to change the mouse-down tracking state of a QuickTime VR movie. Use QTVRMouseDown and QTVRMouseUpExtended (next) to handle the mouse button's being clicked and released.
You can use the QTVRMouseUpExtended function the same way you use the QTVRMouseUp function, to handle the user's releasing the mouse button while the cursor is in a QuickTime VR movie for which mouse-down tracking is disabled.
The QTVRMouseUpExtended function uses the same intercept as the QTVRMouseUp function but has two additional parameters. Applications that intercept QTVRMouseUpExtended should always check the paramCount field to make sure it is 5 before using the last two fields.
Internally, QuickTime VR always uses the QTVRMouseUpExtended function instead of QTVRMouseUp . Developers implementing their own mouse down tracking don't need to use the extended version unless they also intercept the procedure and need the added parameters.
OSErr QTVRMouseUpExtended (
QTVRInstance qtvr,
Pointpt,
UInt32*hotSpotID,
WindowPtr w,
UInt32 when,
UInt16 modifiers);
The QTVRMouseUpExtended function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0. QTVRMouseUpExtended also performs any other tasks that are typically performed when the user releases the mouse button after clicking it when the cursor is in a QuickTime VR movie.
| Previous | Chapter Contents | Chapter Top | Next |